Managing TEX Software Development Projects

During the past few years, many articles and books have been written about managing software development projects. Software development projects using TEX require some special attention. This presentation looks at the entire software development life cycle as it applies to TEX and the following issues in particular: requirements specification, design specification, coding standards, code review checklist. Requirements specification The first step in any software development project should be to create a document known as a requirements specification. This document defines the project in very broad terms. A copy of the requirements specification should be given to everyone involved in the project; any time a requirement changes, everyone involved should be informed of the change by receiving an updated requirements specification document. The requirements specification should include: Description. I am amazed at how difficult it is to describe some projects. If it is not possible to write down a simple paragraph that gives a valid description of the project, that project is not well defined and has a high probability of getting out of control. Project goal. Once the project is described a goal or goals can be defined: “If you don’t know where you are going, then how can you know when you get there?” Defining the project goal can force important issues to surface at the start of the project. A written project goal provides a means to objectively measure the success or failure of a project. Needless to say, the project goal should be documented and understood by all members of the software development team as well as the project manager. Failure to have a documented goal will lead to feature creep and project drift. Overview of problems to be solved. Describe the fundamental problems that need to be solved. Converting the existing data into a usable format may be a real challenge. Word processing files, poorly organized databases with little or no documentation, and spreadsheets can, and often are, the only available format for the data. All must be converted into a format suitable for typesetting with TEX. Tasks/Functions. Specify the tasks or functions the macros perform. For example, if there are any extracted indexes or page cross references they should be defined. Current mode of operation. It is useful to know the current mode of operation. This avoids the problem of creating a solution that cannot be easily integrated into the working environment of the user. For example, if the user is a hard-core plain TEX user, providing a set of macros that only work under LATEX would not be an appropriate solution. Communications. Does the user expect the data back in some other format? One rather large project that I was involved in required converting data from a proprietary typesetting format into SGML, typesetting a book, and producing an electronic version of the data on CD. We finished the book and the CD and figured we were done for the quarter when the client called up and asked us about the “mag-tape version”? Our marketing department had forgotten to tell us that we had to create yet another deliverable. The data was to be delivered on an IBM formatted 6250 BPI magtape with a specific tape label. The requirements document should have specified that deliverable. Unfortunately it did not, and we had to scramble to pull together the resources to complete the project. If the data undergoes any conversion processes it is important to specify the life cycle of the data and its changes. This means that the date (and possibly the time) when the data is frozen for production should be specified. If the data is modifed for typographic reasons during the production process, it must be specified if the original data is to be updated to match the typographic changes. For example, if the data is in SGML or XML it is common to add processing instructions to the data to help with the typography. It is sometimes necessary to make structural changes in tables, particularly CALS SGML tables, to make 1 Continuous Acquisition and Life-Cycle Support (formerly Computer-aided Acquisition and Logistics Support) (CALS) is a Department of Defense (DoD) strategy for achieving effective creation, exchange, and use of digital data for weapon systems and equipment. MIL-PRF-28001C is the military stanTUGboat, Volume 20 (1999), No. 3— Proceedings of the 1999 Annual Meeting 299 Managing TEX Software Development Projects them typeset properly. Changes of this type require complex changes to the source. If the data must be returned in a format that could be used again, the returned data must include the structural changes to the table elements. Another example involves the creation of a printed book and an electronic product, e.g. CDROM. Typographic changes due to typesetting the book may need to be reflected in the CD. Failure to document this requirement can lead to serious problems if the products get out of sync with each other. Ease of use. Specify how experienced with TEX the user of the macros should be. It is all too easy to create macros that only an expert can use. Occasionally, however, it is appropriate to create complex macros. The key is to document the expertise needed, since the level of experience of the user also defines the amount of detail that the documentation needs. Hardware/Software. Specify the hardware platform(s), operating system(s), and implementation(s) of TEX that the macros will run on. This is important if you are using some of the modified implementations of TEX like ε-TEX, Omega, or PDFTEX. Some implementations of TEX are compiled for a particular memory size. Other implementations are configurable. In either case, the minimum and recommended TEX memory size should be specified. This will let the user know if they have to use a larger version of TEX or reconfigure their existing version. TEX has a very small memory footprint by today’s standards. Unfortunately some of our users have just about everything running on the PC at one time. One of our users has the following programs running at all times: Excel, Word, Outlook, Internet Explorer, and several other proprietary pieces of software. “Bloatware” software packages can use up tremendous amounts of local disk space and memory. Attempt to define the possible interactions that might occur if other software packages are running. Define the amount of both network and local hard disk space required. dard for CALS markup requirements. A soft copy of this is available at: http://www-cals.itsi.disa.mil/core/ standards/28001C.pdf Because CALS tables are designed to support the entire DoD they are very complex and difficult to use. Quality. Outline in broad terms the rules for word, paragraph, column, and page breaking. Performance. TEX is a high-performance typesetting system. Usually there is no need to worry about performance. However, the generation of PDF pages on demand by a web server can become a performance issue. List all performance criteria. Compatibility and migration. Specify if the macros are based on plain or LATEX or something else. Specify if the macros have to be compatible with any other macro package. If the macros are a replacement/upgrade of an existing package specify what amount of re-learning will be required of users as they migrate their data to the new package. International. Specify the need to support running and/or continued heads that may include support for R © and TM as well as accented characters. Specify how R © and TM are to be typeset: superscript or not, serif or sans-serif or font dependent. Itemize the languages to be supported. Each language requires it own hyphenation dictionary. The encoding of the input data should be defined. Determine if the data uses the Latin-1 encoding or some other format, e.g. UTF-8. There is a lot of data with accented characters that uses MS-DOS code page 437 or 850. This data is not compatible with the TEX standard encoding or 8r, used with most PostScript fonts. The way the data is encoded should be documented. Service and support. Itemize the level of service and support. The days and hours when support is available should be listed in detail. Pricing/Licensing. Define the ownership of the macros. Specify the method by which the source code will be provided and if the source code can be de-commented. Design specification Creating the design specification document can be done in parallel with creation of the requirements specification document, but it should not precede it. It is important to understand what is required prior to defining the design of the pages. 2 The term “code page” refers to the keyboard and display encoding. When MS-DOS was developed there were no accepted standards for the layout of accented characters. Code page 437 was the default layout for the version of MS-DOS that what shipped to the United States, and code page 850 was the default layout for Wester Europe. 300 TUGboat, Volume 20 (1999), No. 3— Proceedings of the 1999 Annual Meeting Jeffrey McArthur Publishers often provide design specifications, but publisher-supplied design specifications are often incomplete, vague, and ambiguous. Even when the publisher provides such information, a document should be created that defines all the details required by the project. Documenting the specifications also gives the typesetter a mechanism to generate additional revenue when the publisher makes changes at the last minute. Description. Give a detailed description of the typeset pages. Output format. Define the output medium. Resin-coated paper and film are still used as well as electronic formats. The design specification document should unambiguously define the format of electronic files. There are many possible standard electronic formats: PostScript, PDF, or separate EPS files. If the deliverable is in PostScript, identify which PostScript level 1, 2 or 3 is required, and if the files are to be DSC-compliant (Document Structure Convention). Specify how many pages will be in each output file. If the final deliverable to the printer is to be electronic files, it is important to establish a dialogue early in the process with the printer’s technical staff in order to determine the specific file formats needed. Covers/Spines. State if book covers and/or spines are part of the deliverable. Page size. Define the physical size of the page. In PostScript this is also the bounding box. If there are crop marks, the size of the physical page will need to be larger than the size of the trimmed page. The size of the trimmed page should also be defined. PostScript and imposition software may have additional requirements. The bounding box of the printed page may or may not need to include the crop marks, depending on the needs of the imposition software. Crop marks. Specify if crop marks are needed and where they are to be located. Today, many web press printers want crop marks, but they must 3 Some imagesetters limit the number of pages they can process in a single file. Often long runs must be broken into ten or twenty page batches. When this happens, the design specification document should also define the file naming convention for the multiple pieces. be located one-eighth of an inch outside the page. Specify the location of the crop marks and what they should look like. Color separations and registration marks. Define the number of color separations and what information is printed on each separation. Registration marks should also be specified. The use of spot color or highlighting also needs to be defined. Screens. Specify if there are any screens on the pages or if the pages are to be set on colored paper. Also define the amount that the screens must extend beyond the trim size. Bleed tabs. Define the number, size, and placement of any bleed tabs as well as the amount that the tab should “bleed” beyond the trim size. Makeup. Define the number of columns per page for each section of the book. The rules for starting a new column, new page, and new right-hand page should all be specified. Fonts. Define what fonts are to be used. If the output is PostScript or PDF, the document should also specify if the fonts are to be embedded in the document. Also specify if embedded fonts must be the entire font or if the font can be a subset of only the characters used by the document. Running heads. Define the running heads. The rules for any alpha-omega or dictionary heads should be specified. The document should also define if math, accented characters, or other complex textual material can occur in the running heads since these may require particular attention. Even if there is initial agreement that there will be no math in the running heads, this may change later in the process. Any changes to design specification must be agreed to by all parties. Continuation heads. Define the number and type of continuation heads. As with running heads, the document should define if math, accented characters, or other complex textual material can occur in continuation heads. Sorting. If the data is to be sorted, the rules for sorting must be defined. Particular attention should be made to rules for ignoring leading articles such as “a”, “an”, and “the”, casing and punctuation. The sorting order for names can be particularly complex and must be defined. Sorting languages like Chinese can be particularly challenging since it can be sorted in either radical then stroke order or stroke then radical order. The order is dependent upon the publisher’s TUGboat, Volume 20 (1999), No. 3— Proceedings of the 1999 Annual Meeting 301 Managing TEX Software Development Projects preference. Dealing with sorting and punctuation in Chinese is particularly painful. Japanese has even more complicated sorting requirements. All of these need to be specified if the sorting involves Chinese, Japanese, or Korean. Cross-references and hypertext links. Define the types of cross-references. The document should define if they are simple references, or actual page cross-references or even hypertext links. The formatting style for hypertext links should be defined. Extracted indexes. Define any extracted indexes. The sorting order for each extracted index must be clearly described and all exceptions noted. Graphics and line art. Define the parameters for line art. If there are specific limits on the art size or shape they must be documented. The acceptable formats for the artwork should be specified. If the artwork is to be scanned, the scanning resolution should be specified as well as the delivery format. If there is an approval process associated with the artwork it should be clearly spelled out. Hyphenation. Define the rules for hyphenation. Any multi-lingual document requires special attention to defining the hyphenation rules. Widows and orphans. The rules for breaking paragraphs, columns, and pages should be defined in detail. Special attention should be devoted to pages that run short or long. Additional breaking and grouping logic. Describe any logic that may be required for grouping. For example, it may be undesirable to break address listings except at specific places. For example: the city, state or province, and postal code should sit as a block, except when they will not fit, and then it should break following the city. The rules for addresses outside of the United States and Canada should be defined in detail. Blank pages. The direct-to-plate technology does not come without a price: imposition software demands consistency. Often it is necessary for the final deliverable electronic pages to include blanks. When a section of a book is defined to start on a new right-hand page, the typesetting macros may need to output a blank page instead of just incrementing the folio. Bleed tabs, crop marks, and screens complicate the process. 4 Advertisements in books are generally artwork that must be approved prior to printing in the finished book. Front and back matter. Cover pages, copyright pages, and dedications are often created using WYSIWYG software. If the book is to be printed using direct-to-plate technology these pages may need to be integrated into the electronic files for the body of the book. How these pages are to be delivered and who will be responsible for the integration must be documented. Typesetting deliverables. Define how the finished pages are to be delivered. In the case of film or photographic paper, include the shipping address and how the package is to be shipped. If the deliverable is electronic, specify how the data is to be transferred or shipped. Define the acceptable media: floppy, zip-disk, CD-ROM. If the files are to be electronically transmitted, list the email address or the ftp site to which the data is to be sent. If the data is to be transferred through a firewall, the security measures should be specified. Features/Enhancements. Define possible future features or enhancements that could be made to the typesetting macros. Exit conditions. The printer has the final word on the design specification document. The location of crop marks, bleed tabs, registration marks, and screens may need to be adjusted to meet the demands made by the printing press. Sample pages should be sent to the printer for their approval as soon as possible in the process.